home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK2.toast / Development Kits (Disc 2) / QuickTime™ VR 2.0 SDK / About the QuickTime™ VR 2.0 API next >
Encoding:
Text File  |  1997-05-22  |  9.0 KB  |  133 lines  |  [ttro/ttxt]
  1. About the QuickTime™ VR 2.0 API
  2.  
  3.  
  4. •• Using the QuickTime VR API and Sample Code ••
  5.  
  6. Important:  Any C/C++ code compiled against the QuickTime VR headers *REQUIRES* headers and libraries from Quicktime 2.5 or newer; QuickTime 2.5's interfaces are included here. The sample code also requires updated interfaces for several additional APIs. All of these are included in a folder called Updated Interfaces.
  7.  
  8. There are two ways to use the new interfaces; you can either replace and add to the existing interfaces in your environment, or use the Updated Interfaces folder separately and make sure that it is first in your interfaces search path. If you chose the latter and are using CodeWarrior, we recommend you drop the Updated Interfaces folder in "{compiler ƒ}:Mac OS Support:"; this is where the enclosed sample code projects are set to search first.
  9.  
  10. The Sample Code
  11.  
  12. All of the sample code uses CodeWarrior 10 projects (IDE v1.7), and should work fine with either of the above mechanisms for updating to the Updated Interfaces; if you chose to replace your existing interfaces, you may get an access path warning which can be ignored.
  13.  
  14. Note that if you get compiler errors in areas containing the word "Atom", the project didn't find the updated headers.
  15.  
  16. The sample code is all designed so that it can compile directly from the directory structure in which it was placed on the CD; that is, with the "QuickTime™ VR API" folder as a sibling to the "Sample Code" folder.
  17.  
  18. For more information on the samples, see their respective Read-Me files.
  19.  
  20. The API
  21.  
  22. The QuickTime VR API consists of the following files:
  23.  
  24. -- QTVR.h
  25. The QuickTime VR API interfaces header for C/C++.
  26. -- QTVRFrmt.h
  27. The QuickTime VR File Format data structures header for C/C++; not needed to play back existing files.
  28. -- QuickTimeVRLib
  29. The shared library to link against for PowerPC development.
  30. -- QTVR.MW.c.o
  31. The 68k object file to be linked in for use with MetroWerks compilers.
  32. -- QTVR.SC.c.o
  33. The 68k object file to be linked in for use with SC under MPW.
  34.  
  35.  
  36. Documentation Errata
  37.  
  38. Page 1-48:  kQTVRInteractionPanTiltSpeed is valid only for panoramas, and not objects.
  39.  
  40. Pages 1-86 to 1-88, 1-90 to 1-93:  QTVRMouseEnter, QTVRMouseWithin, QTVRMouseLeave, QTVRMouseDown, QTVRMouseStillDown, and QTVRMouseUp all have an additional WindowPtr parameter, w. The new prototypes read as follows:
  41.  
  42. OSErr    QTVRMouseEnter (QTVRInstance qtvr, Point pt, UInt32 *hotSpotID, WindowPtr w);
  43. OSErr    QTVRMouseWithin (QTVRInstance qtvr, Point pt, UInt32 *hotSpotID, WindowPtr w);
  44. OSErr    QTVRMouseLeave (QTVRInstance qtvr, Point pt, WindowPtr w);
  45. OSErr    QTVRMouseDown (QTVRInstance qtvr, Point pt, UInt32 when, UInt16 modifiers, UInt32 *hotSpotID, WindowPtr w);
  46. OSErr    QTVRMouseStillDown (QTVRInstance qtvr, Point pt, UInt32 *hotSpotID, WindowPtr w);
  47. OSErr    QTVRMouseUp (QTVRInstance qtvr, Point pt, UInt32 *hotSpotID, WindowPtr w);
  48.  
  49. The parameter pt is the current location of the cursor, in the local coordinates of the graphics world w.
  50.  
  51. When intercepting these functions, w is in the appropriate location in the intercept record.
  52.  
  53. The WindowPtr parameter was added because it is possible for the movie and its controller to exist in different graphics worlds, and so it is not possible to simply assume that pt is in the local coordinates of the graphics world of the movie.
  54.  
  55. Page 1-152:  Under MyImagingCompleteProc/Special Considerations, it is stated that if kQTVRImagingDirectDraw is true, then images are drawn directly to the destination without your MyImagingCompleteProc function being called; this is no longer true. QuickTime VR now temporarily overrides the setting of kQTVRImagingDirectDraw if a PrescreenImagingCompleteProc is installed.
  56.  
  57. Page 2-23:  In some cases, the QuickTime VR movie controller will suppress a button even when it has not been explicitly supressed via a flag; for example, the speaker button is suppressed if there is no sound track in movie. If mcFlagQTVRExplicitFlagSet is set when mcActionSetFlags is called, the flags parameter will have a different meaning: for each bit set in the flags parameter, the controller will not attempt to do anything intelligent regarding displaying or hiding that feature/button, but will instead just hide or show the button based on the setting of the equivalent flag in the flags parameter of a call to mcActionSetFlags without mcFlagQTVRExplicitFlagSet.
  58.  
  59. Note that this allows you to use the usual mcActionSetFlags constants for the various features' bit positions, but that the term 'suppress' is incorrect and may be confusing when used in conjunction with the mcFlagQTVRExplicitFlagSet flag.
  60.  
  61. As an example, this code forces the speaker button to be shown even when there is no sound track in a movie:
  62.  
  63. long myFlags;
  64.  
  65. // Get the current Flags
  66. myFlags = 0;
  67. MCDoAction(activeMovie->movieController, mcActionGetFlags, &myFlags);
  68.  
  69. // Un-suppress the speaker button - this is the default, but we're making sure.
  70. MCDoAction(activeMovie->movieController, mcActionSetFlags,
  71.   (void *)(myFlags & !mcFlagSuppressSpeakerButton));
  72. // At this point, because the button isn't explicitly suppressed, it may or may not show up
  73. //  depending on whether a sound track is present
  74.  
  75.  
  76. // Get the current ExplicitFlags set
  77. myFlags = mcFlagQTVRExplicitFlagSet;
  78. MCDoAction(activeMovie->movieController, mcActionGetFlags, &myFlags);
  79.  
  80. // Add the speaker button ExplicitFlag - note that this works only on QuickTime VR movies
  81. MCDoAction(activeMovie->movieController, mcActionSetFlags,
  82.   (void *)(myFlags | mcFlagQTVRExplicitFlagSet | mcFlagSuppressSpeakerButton));
  83.  
  84. // This says: don't try and figure out whether to display the button, just take whatever
  85. //  we set before (not off, aka 'on') and make it so.
  86. // That is, for myFlags, this IS an ExplicitFlagSet, and DO make the SpeakerButton flag explicit.
  87. // Don't be confused by the word 'suppress'; we're just using this constant to specify a bit position.
  88.  
  89. Pages A-1 to A-2, A-15:  Object nodes make use of the "panorama" hotspot cursors, resource IDs -19699 to -19685; the "object" hotspot cursors, resource IDs -19898 to -19895, are never used.
  90.  
  91.  
  92. Addendum:  Show Hotspots uses a MovieDrawingCompleteProc for object nodes, of which a movie can only have one; if you need to use a MovieDrawingCompleteProc for a movie in your application, you can either suppress the Show Hotspots button, or intercept the button's actions and implement your own Show Hotspots functionality. Panorama nodes do not use a MovieDrawingCompleteProc, and draw their hotspots prior to an application's PrescreenImagingCompleteProc being called if present.
  93.  
  94.  
  95. Hints & Tips:
  96.  
  97. With a transition enabled (i.e., the swing transition), as without, it is important to set the target FOV before the tilt and pan angles, in order that the latter not be limited by the former.
  98.  
  99.  
  100. General Usage and Technical Notes
  101.  
  102. The VR Programming with QTVR 2.0 book is included in Adobe Acrobat 3.0 PDF format. This file has links to QuickTime™ VR movies; for those movies to play, you must first have the QuickTime™ VR extension installed and have MoviePlayer present on your machine.
  103.  
  104. For futher information on the QuickTime™ VR 2.0 extension, please see About QuickTime™ VR 2.0.
  105.  
  106.  
  107. Transition Issues: Using the QuickTime VR API to Program for Windows and the Web
  108.  
  109. The QuickTime VR API works on QuickTime VR 1.0 content as well as QuickTime VR 2.0 content. However, to run programs created using the QuickTime VR API, the user will need the QuickTime VR 2.0 system extension for the platform they are using: Macintosh, 32-bit Windows, or 16-bit Windows.
  110.  
  111. For Macintosh, the user will need the QuickTime VR 2.0 system extension included in this package. Distribute the extension with your application and include it in your program's installation procedure. 
  112.  
  113. For 32-bit Windows, the user will need the upcoming QuickTime VR 2.0.1 extension for 32-bit Windows. This extension depends on an upcoming release of QuickTime that is expected to be available in the second quarter of 1997; the QuickTime VR 2.0.1 extension for 32-bit Windows will follow shortly after. Distribute the extension with your application and have the user install it. Also, check for the upcoming version of QuickTime; consider including it with your program so the user can install it as well.
  114.  
  115. For 16-bit Windows, new versions of QuickTime and QuickTime VR for 16-bit Windows are under consideration and may be released later in 1997.
  116.  
  117. For the Web, the QuickTime VR API does not work directly. Apple is investigating options such as Java, Macromedia's ShockWave, and other means to support the distribution of multimedia programs with QuickTime VR content over the Web. 
  118.  
  119. For more information and an update on these issues, please see: 
  120. - The QuickTime Web site, http://quicktime.apple.com 
  121. - The QuickTime VR Web site, http://quicktimevr.apple.com 
  122. - The free QuickTime and QuickTime VR developer mailing lists; subscription instructions are available on the respective Web sites 
  123. - The Apple developer support program, http://devworld.apple.com/dev/dev.shtml.
  124.  
  125.  
  126. "Acrobat(R) Reader copyright (C) 1987-1996 Adobe Systems Incorporated. All 
  127.     rights reserved. Adobe and Acrobat are trademarks of Adobe Systems Incorporated."
  128.  
  129.  
  130. QuickTime VR 2.0 API
  131. 2/24/97
  132. BDW
  133.